Skip to content

J.4: the A64 primary spec from Sail Arm, and encoder contracts (spec only) - #186

Open
atiernan wants to merge 8 commits into
claude/x64-specfrom
claude/a64-spec
Open

atiernan wants to merge 8 commits into
claude/x64-specfrom
claude/a64-spec

Conversation

@atiernan

Copy link
Copy Markdown
Member

JIT plan item J.4, first half: clazel-a64's primary spec, transcribed from the vendored Sail Arm model only, plus the contracts for the encoder and decoder (rule 3). There is no implementation yet, and the crate stays at tier 0.

Stacked on #179, which holds the sources. Merge that PR first, or retarget this one afterwards.

What's here

  • src/spec.rs: about 2,400 lines. Every definition cites its Sail decode or execute function and the v8_base.sail helper it uses. All instructions come in 64- and 32-bit forms.
    • Arithmetic: ADD/ADDS/SUB/SUBS (shifted register and immediate), with CMP, CMN and MOV to/from SP as aliases; MADD/MSUB (MUL) and SDIV/UDIV.
    • Logic: AND/ORR/EOR/ANDS (shifted register), with MOV and TST as aliases.
    • Shifts and bit fields: LSLV/LSRV/ASRV, and SBFM/UBFM with their aliases.
    • Constants: MOVZ/MOVK. J.4's list names no way to load a constant, so these were added.
    • Conditional select: CSEL/CSINC/CSINV/CSNEG, with CSET as an alias.
    • Loads and stores: LDR/STR of W, X and D registers, with a scaled unsigned immediate or a register offset.
    • Branches: B, B.cond, CBZ/CBNZ, and RET through X30 only.
    • Scalar double FP: FADD/FSUB/FMUL/FDIV/FSQRT/FCMP, FMOV/FABS/FNEG, FMOV between X and D, and SCVTF/FCVTZS.
    • Floating point: exact, with no uninterpreted functions and no axioms. A Real is a rational or the square root of one, so FSQRT is the exact correctly rounded square root.
  • src/examples.rs: 26 encodings checked against the usual assembler words, plus AddWithCarry and ConditionHolds cases.
  • src/contract.rs and src/api.rs: the encoder and decoder contracts, on a body-less trait with no escape hatch. They work on 32-bit words: encode_instr(&Instr) -> u32 and decode_instr(u32) -> Option<Instr>.

For the spec reviewer, first

  1. FPCR is fixed to 0: round to nearest even, no flush-to-zero, AH = NEP = 0. J.7's enter stub must keep it, just as it must set MXCSR on x86-64.
  2. Top-byte-ignore is not modelled. A tagged address faults in the model, which is stricter than Linux hardware (TBI0 = 1).
  3. SP is not allowed as a load/store base, because of SP alignment checking.
  4. The canonical-encoding choices, listed at valid_instr:
    • a shift of 0 is written LSL;
    • an immediate of 0 has sh = 0;
    • MOVZ #0 has hw = 0;
    • the AL and NV conditions are never used;
    • a register offset uses UXTX (011);
    • RET is through X30 only.
  5. Two properties are stated but not proven: canonical_injective and encode_fits. They get proven with the implementation.

For the hardware tests to settle

  • FCVTZS of a NaN gives 0 in Sail, and an infinity saturates.
  • SDIV/UDIV by zero gives 0 without trapping, and INT_MIN / -1 wraps.
  • Sail's decoder for unsigned-offset LDR/STR calls the post-index execute function. Its body is the same text, and the spec cites the function actually called.

Left out

  • Logical immediates; MOVN (it would need a canonical rule, since it overlaps MOVZ); BIC/ORN/EON.
  • Byte and halfword loads and stores, pre- and post-indexed addressing, LDP.
  • TBZ, BL and BR.
  • Single and half precision, FMADD, FCMPE, UCVTF/FCVTZU, and anything SIMD.

Not vendored

Sail's standard library (arith.sail, vector_dec.sail, real.sail from rems-project/sail lib/), which defines UInt/SInt, the shifts, floor and sqrt. The spec uses their standard meaning and says so in its header. No other Sail Arm file is needed.

Verification

  • Verus, on a fresh target dir in WSL: verification results:: 11 verified, 0 errors. That is the example proofs; spec fns and the body-less trait add nothing to the count.
  • Verus also prints 110 "missing documentation" warnings, which point at the Instr and Real enums. They look like the field accessors Verus generates. They don't appear in the normal build.
  • cargo xtask check: STATIC CHECKS PASSED. Build, clippy -D warnings, rustfmt and cargo test -p clazel-a64 are clean.
  • cargo xtask verify --changed was not run, because the vstd dependency changes Cargo.lock. CI's full verification is the check, and its proof jobs need approval.

🤖 Generated with Claude Code

atiernan and others added 2 commits November 17, 2026 11:50
Transcribed from the vendored Sail Arm model (Armv9.4-A, rems-project/sail-arm
5416ef6b), citing the Sail function for every definition: the machine state
(X0-X30, SP_EL0, PC, NZCV, V0-V31, memory as a partial map), the semantics
of each instruction of the subset as one step, and the canonical 32-bit
encoding with the field values the subset admits.

The subset: ADD/ADDS/SUB/SUBS (shifted register, immediate), MADD/MSUB,
SDIV/UDIV, AND/ORR/EOR/ANDS (shifted register), LSLV/LSRV/ASRV, SBFM/UBFM,
MOVZ/MOVK, CSEL/CSINC/CSINV/CSNEG, LDR/STR of W, X and D registers with an
unsigned scaled immediate or a register offset, B, B.cond, CBZ/CBNZ, RET,
and scalar double FADD/FSUB/FMUL/FDIV/FSQRT/FMOV/FABS/FNEG/FCMP, FMOV
between X and D, SCVTF and FCVTZS. 32- and 64-bit forms.

FPCR is fixed at 0 (round to nearest even, no flush to zero, no default
NaN, no FEAT_AFP behaviour, no traps); every modelling choice is listed in
the header. Floating point is exact, FSQRT included (a Real is a rational
or the square root of one). The crate stays at tier 0. Verus: 11 verified,
0 errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
contract.rs states what the encoder and decoder must be proven to meet, in
terms of spec.rs: the encoder emits only the canonical word of a valid
instruction; the decoder returns Some only for a canonical word and None
only when no valid instruction encodes to it. canonical_injective and
encode_fits are stated, to be proven with the implementation. api.rs is
the body-less trait A64Codec carrying them, so Verus accepts it with no
escape hatch. No implementation; the crate stays at tier 0. Verus: 11
verified, 0 errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan
atiernan changed the base branch from claude/jit-isa-sources to claude/x64-spec November 17, 2026 13:11
@atiernan
atiernan added this pull request to stack #188 November 17, 2026 13:11
@atiernan
atiernan temporarily deployed to full-verification November 17, 2026 13:22 — with GitHub Actions Inactive
atiernan and others added 2 commits November 17, 2026 20:20
CI's proof job requires a mutations.json for every crate Verus checks.
Three mutations (AddWithCarry's carry inverted, its V flag dropped,
B.cond's imm19 at bit 4), each killed by an existing proven example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan
atiernan temporarily deployed to full-verification November 18, 2026 13:38 — with GitHub Actions Inactive
atiernan and others added 2 commits November 20, 2026 19:40
Both add-with-carry certificates "did not build" in CI: compute_only left
`pow(2, 32)` unevaluated, because vstd's `pow` (under `pow2`) is
`#[verifier::opaque]`. The certificates now list it in `reveal`, which
mutate.rs provides for opaque items a witness evaluates through.

Locally (Verus 0.2026.10.04): 11 verified, 0 errors; 3 mutations, 3 killed
by a theorem with certificates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan
atiernan temporarily deployed to full-verification November 20, 2026 19:50 — with GitHub Actions Inactive

This branch was previously deployed

1 inactive deployment
full-verification — 358db261 Deployed Nov 20, 2026 by atiernan via Approve the proofs #617
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant